%% $Id$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarksopen,bookmarksnumbered]{hyperref}
}{}

%% do we have the `fancyhdr' or `fancyheadings' package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id$
\setDate{\rcsInfoLongDate}
}{
\setDate{2018/06/28}
\message{package rcsinfo not present, discard it}
}

\setVersionWord{Version:}  %%% that's the default, no need to set it.
\setVersion{=PACKAGE_VERSION=}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{Name}{1}{hpctoolkit}{The HPCToolkit Performance Tools}{The HPCToolkit Performance Tools}{HPCToolkit}

\textbf{HPCToolkit} is a collection of performance analysis tools for node-based performance analysis.
It has been designed around the following principles:
\begin{itemize}

\item \textbf{Be language independent.}
\item \textbf{Avoid code instrumentation.}
\item \textbf{Avoid blind spots.}
\item \textbf{Provide context for understanding layered and object-oriented software.}
\item \textbf{Support multiple performance measures to prevent myopic interpretation.}
\item \textbf{Display user-defined derived performance metrics for effective analysis.}
\item \textbf{Take a top down approach to performance analysis.}
\item \textbf{Use hierarchical aggregation to mitigate approximate attribution.} 
\item \textbf{Ensure that measurement and analysis can scale to very large programs and executions.}

\end{itemize}

More detailed explanation of these design principles is available
in papers on the HPCToolkit website at \HTMLhref{http://hpctoolkit.org}{hpctoolkit.org}.

\end{Name}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Description}

A typical performance analysis session consists of:
\begin{enumerate}
\item \textbf{Measuring execution costs.}  
\HTMLhref{hpcrun.html}{\Cmd{hpcrun}{1}} uses statistical sampling to collect with low overhead and high accuracy
a set of \emph{call path profiles},
i.e. measurements of hardware resource consumption (costs) together with the call paths at which consumption occurred.
For statically linked applications \HTMLhref{hpclink.html}{\Cmd{hpclink}{1}} serves the same purpose.

\item \textbf{Analyzing source code structure.} 
\HTMLhref{hpcstruct.html}{\Cmd{hpcstruct}{1}} discovers static program structure such as procedures and loop nests
from binary code in the application's executable.
It takes into account optimizing compiler transformations such as restructuring of procedures and loops
for inlining, software pipelining, multicore parallelization, and offloading to GPUs.

\item \textbf{Attributing measured costs to source code structure.} 
\HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}} combines \Prog{hpcrun}'s dynamic profiles
with \Prog{hpcstruct}'s static program structure
to attribute measured costs incurred by the optimized object code
to meaningful source code constructs such as procedures, loop nests, and individual lines of code.
The result of attribution is an \emph{experiment database} stored in a file system directory.

\item \textbf{Visualizing attributed costs in source code or timeline views.}
\HTMLhref{hpcviewer.html}{\Cmd{hpcviewer}{1}} and \HTMLhref{hpctraceviewer.html}{\Cmd{hpctraceviewer}{1}}
are tools for presenting the resulting experiment databases.
\Prog{hpcviewer} displays measurements in outline form,
each entry attributing costs to a source code construct by line number
and linked to a display of corresponding application source code.
\Prog{hpctraceviewer} displays measurements as a two dimensional timeline
with execution progress aalong the horizontal axis
and the application's parallel threads along the vertical axis.
The visualization step may be done  interactively with either tool on a personal computer.
even if the application must run in batch on a large computing cluster.
To this end, experiment databases are self contained and relocatable,
even containing a copy of the application source code,
and the \Prog{hpcviewer} and \Prog{hpctraceviewer} tools
are platform-independent (via Eclipse RCP)
and lightweight enough for good interactive performance on a laptop.

\end{enumerate}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples}

Assume we have an application called \Prog{zoo} whose source code is located in \emph{path-to-zoo}.
First compile and link your application normally with full optimization
and as much debugging information as possible.
Typically this involves compiler options such as \verb+-O3 -g+.
(See \HTMLhref{hpcstruct.html}{\Cmd{hpcstruct}{1}} for options for specific compilers.)
Then perform the following steps.

\begin{enumerate}

\item \textbf{Measure}.
Profile with \HTMLhref{hpcrun.html}{\Cmd{hpcrun}{1}}.
Assume you wish to measure two different sets of resources,
which will require two measurement runs.
\Prog{hpcrun} always collects the data needed for \Prog{hpcviewer},
but if you want to use \Prog{hpctraceviewer} you must add
the \Prog{-t} / \Prog{--trace} option to collect additional data.
\begin{verbatim}
  hpcrun -t <event-set-1> zoo
  hpcrun -t <event-set-2> zoo
\end{verbatim}

\HTMLhref{hpcrun.html}{\Cmd{hpcrun}{1}} by default puts its results into a measurement directory
named \File{hpctoolkit-appname-measurements},
so the two sets of measurements are combined automatically.

\item \textbf{Analyze}. 
Use \HTMLhref{hpcstruct.html}{\Cmd{hpcstruct}{1}} to discover program structure
and write it to the file \File{zoo.hpcstruct}.
Although \Prog{hpcstruct} has a number of advanced options, it is typically run with none.
The application's source code directory is passed as the last argument.
\begin{verbatim}
  hpcstruct zoo
\end{verbatim}

By default the generated structure file is named \File{zoo.hpcstruct}.

\item \textbf{Attribute}.
Create an experiment database using \HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}}.
(The version of \HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}} must match
the version of \HTMLhref{hpcrun.html}{\Cmd{hpcrun}{1}}.)
Use the \Prog{-I} option to specify the location of \Prog{zoo}'s source code
and the \Prog{-S} option to specify the structure file produced in the previous step.
The neasurement directory is specified as the last argument.
By default the generated experiment database is named \File{hpctoolkit-zoo-database}.
\begin{verbatim}
  hpcprof -I path-to-zoo/+ -S zoo.hpcstruct hpctoolkit-zoo-measurements
\end{verbatim}

\item \textbf{Visualize}.
Visualize the experiment database in either source or timeline view,
on any machine where you've copied the database:
\begin{verbatim}
  hpcviewer hpctoolkit-zoo-database
  hpctraceviewerviewer hpctoolkit-zoo-database
  
\end{verbatim}
In \Prog{hpcviewer} you may also view "derived metrics",
i\.e\. combinations of measured metrics which are computed on the fly.
See \emph{The hpcviewer User Interface} Guide for more information.

\end{enumerate}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\section{Notes}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{See Also}

\HTMLhref{hpcrun.html}{\Cmd{hpcrun}{1}},
  \HTMLhref{hpclink.html}{\Cmd{hpclink}{1}} \\
\HTMLhref{hpcstruct.html}{\Cmd{hpcstruct}{1}} \\
\HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}},
  \HTMLhref{hpcprof-mpi.html}{\Cmd{hpcprof-mpi}{1}} \\
  \SP\SP \HTMLhref{hpcsummary.html}{\Cmd{hpcsummary}{1}} \\
\HTMLhref{hpcviewer.html}{\Cmd{hpcviewer}{1}},
  \HTMLhref{hpctraceviewer.html}{\Cmd{hpctraceviewer}{1}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version}

Version: \Version

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{License and Copyright}

\begin{description}
\item[Copyright] \copyright\ 2002-2019, Rice University.
\item[License] See \File{README.License}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors}

Email: \Email{hpctoolkit-forum =at= rice.edu} \\
WWW: \URL{http://hpctoolkit.org}.

\LatexManEnd

\end{document}

%% Local Variables:
%% eval: (add-hook 'write-file-hooks 'time-stamp)
%% time-stamp-start: "setDate{ "
%% time-stamp-format: "%:y/%02m/%02d"
%% time-stamp-end: "}\n"
%% time-stamp-line-limit: 50
%% End:

